home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1991 …esperately Seeking Seven / Desperately Seeking Seven.2mg / Dev.CD.8 / Essentials / Utilities / GSBug / GSBug.Specs < prev    next >
Encoding:
Text File  |  1990-12-03  |  19.8 KB  |  584 lines  |  [04] ASCII Text (0x0000)
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                                GSBug Version 1.5
  8.                              Current Version 1.5B11
  9.  
  10.  
  11.  
  12.  
  13.  
  14. Version 1.5b11 (DAL)
  15.  
  16.  
  17. You can use SetOSBrk and ClrOSBRK with call names now.  Class-1 names all end
  18. in GS to distinguish them from their class-0 siblings.  Examples:
  19.  
  20.     SetOSBrk #1
  21.  
  22.     SetOSBrk _Create
  23.  
  24.     SetOSBrk #2001
  25.  
  26.     SetOSBrk _CreateGS
  27.  
  28.  
  29. The debugger now changes its own handleUs memory ID during a real-time JSL to 
  30. match the code being stepped.  For example, now you can step over an MMStartUp 
  31. and get the expected ID returned (the application's instead of the debugger's).
  32.  
  33.  
  34. Changed 'D' command to 'I' so it doesn't interfere with typing a hex number
  35. that starts with a D.  The I command toggles the 'ignore REP/SEP instructions
  36. mode' when disassembling.
  37.  
  38.  
  39. Changed parsing for the P (Print screen) command so that it just beeps if there are any 
  40. characters after the P.  (Typing 'put' intead of 'out' can no longer hang your 
  41. system.)
  42.  
  43.  
  44. Put the help screen for MP mode back in.
  45.  
  46.  
  47. The solid flashing cursor in MEM, MP, and BP no longer flashes.  In exchange
  48. for this, special characters (like braces) that happen to be in Inverse don't
  49. flash while you're in the subscreens.
  50.  
  51.  
  52. Added pseudo tool call $0BFF=DebugSetHook (one Long parameter).  The N
  53. ("neat- o") command calls this hook.
  54.  
  55.  
  56. Removed a conditional hard-coded increment of $004002 when X-ing a JSR.
  57.  
  58.  
  59. Added REP #$30 on the two tool-dispatcher-intercept routines.  Making tool
  60. calls in other than full native mode is still not a good idea.
  61.  
  62.  
  63. Fixed real-time breakpoints for most 1-byte instructions and all 16-bit load
  64. immediate instructions.  Previously, they crashed when used with a count
  65. greater than one.
  66.  
  67.  
  68. Please note that */System/System.Setup/GSBug.Setup is *already* loaded 
  69. automatically (has been for quite a while).
  70.  
  71.  
  72.  
  73. Version 1.5b10 (DAL)
  74.  
  75.  
  76. Stepping in emulation mode should be much more reliable now, although it isn't 
  77. perfect (in particular, one place where there's a window of vulnerability is
  78. using X on a JSR in emulation mode, but if you have the I bit set in your P
  79. register there's no problem).
  80.  
  81.  
  82. Having the stack in $01xx works much better now, whether you're in emulation
  83. or not.  This works by frequently stuffing a $80 into $01/0100 (EMULSTACK,
  84. the location the interrupt manager and other things used to set the $01xx
  85. stack when needed).
  86.  
  87.  
  88. If you trace code that actually uses the $01/0100 value to set the stack
  89. pointer, you still have a problem, since your program will start using the
  90. part of the stack that gets toasted on every interrupt.
  91.  
  92.  
  93. You can now type in GSBug even if the Event Manager is on but keyboard
  94. interrupts are off.  Previously this would leave you dead in the water.
  95.  
  96.  
  97. Files created with CSave now have a real filetype/auxtype assignment ($5A/0005).
  98.  
  99.  
  100. Fixed DebugStr to return no error (previously it was returning the high two
  101. bytes of the caller's address as an error).
  102.  
  103.  
  104. Took out code that was checking $C020 (not SLOTREG at $C02D) to see if the
  105. printer slot was switched in.  Makes no sense anyway, because a printer can
  106. legitimately be either an internal or external slot.
  107.  
  108.  
  109. Brought the list of Toolbox call names up to date for System Software 5.0.3
  110. (see changes below).
  111.  
  112.  
  113. Added tool set names (for example, $0002 is Memory Manager).  For some time, 
  114. you've been able to use SetTBrk with a tool set number, to force a break on
  115. every call to that tool set.  Now you can do it by name, too.
  116.  
  117. Examples:
  118.  
  119.     SetTBrk #2
  120.  
  121.     SetTBrk _Memory Manager
  122.  
  123.     ShowBrks
  124.  
  125.  
  126. Saved about 900 bytes by removing many extra copies of the string "Unknown".
  127.  
  128.  
  129. Obsolete call names removed:
  130.  
  131. 1522    TEInsertPageBreak
  132. 2022    TEGetHooks
  133. 2122    TESetHooks
  134. 2222    TEGetDefProc
  135.  
  136.  
  137. Call names corrected:
  138.  
  139. 0D02    RemoveFromOOMQueue
  140. 2115    SelectIText
  141. 1021    VDKeyGetKRCol
  142. 1121    VDKeyGetKGCol
  143. 1221    VDKeyGetKBCol
  144.  
  145.  
  146.  
  147. Call names added:
  148.  
  149. 3603    ReleaseROMResource  3703    ConvSeconds     010A    SANEBootInit
  150. 020A    SANEStartUp         030A    SANEShutDown    040A    SANEVersion
  151. 050A    SANEReset           060A    SANEStatus      090A    FPNum
  152. 0A0A    DecStrNum           0B0A    ElemNum         5D0E    TaskMasterContent
  153. 5E0E    TaskMasterKey       1713    GetDeviceName   1813    PrGetPrinterSpecs
  154. 1913    PrDevPrChanged      1A13    PrDevStartup    1B13    PrDevShutDown
  155. 1C13    PrDevOpen           1D13    PrDevRead       1E13    PrDevWrite
  156. 1F13    PrDevClose          2013    PrDevStatus     2113    PrDevAsyncRead
  157. 2213    PrDevWriteBackground    3013    PrDevIsItSafe   2022    TEOffsetToPoint
  158. 2122    TEPointToOffset     2222    TEGetDefProc    2322    TEGetRuler
  159. 2422    TESetRuler          2522    TEScroll        2622    TEGetInternalProc
  160. 2722    TEGetLastError      2822    TECompactRecord
  161. 0123    MSBoot              0223    MSStartUp       0323    MSShutDown
  162. 0423    MSVersion           0523    MSReset         0623    MSStatus
  163. 0923    SetBasicChan        0A23    SetMIDIMode     0B23    PlayNote
  164. 0C23    StopNote            0D23    KillAllNotes    0E23    SetRecTrack
  165. 0F23    SetPlayTrack        1023    TrackToChan     1123    Locate
  166. 1223    SetVelComp          1323    SetMIDIPort     1423    SetInstrument
  167. 1523    SeqPlayer           1623    SetTempo        1723    SetCallBack
  168. 1823    SysExOut            1923    SetBeat         1A23    MIDIMessage
  169. 1B23    LocateEnd           1C23    Merge           1D23    DeleteTrack
  170. 1E23    SetMetro            1F23    GetMSData       2023    ConvertToTime
  171. 2123    ConvertToMeasure    2223    MSSuspend       2323    MSResume
  172. 2423    SetTuningTable      2523    GetTuningTable  2623    SetTrackOut
  173. 2723    StartMIDIDriver     2823    StopMIDIdriver  04FF    DebugVersion
  174. 06FF    DebugStatus         09FF    DebugStr        0AFF    SetMileStone
  175.  
  176.  
  177.  
  178. Tool Set Names  (You can use these with SetTBrk.)
  179.  
  180. 0001    Tool Locator
  181. 0002    Memory Manager
  182. 0003    Misc Tools
  183. 0004    QuickDraw
  184. 0005    Desk Manager
  185. 0006    Event Manager
  186. 0007    Scheduler
  187. 0008    Sound Tools
  188. 0009    ADB
  189. 000A    SANE
  190. 000B    Integer Math
  191. 000C    Text Tools
  192. 000E    Window Manager
  193. 000F    Menu Manager
  194. 0010    Control Manager
  195. 0011    Loader
  196. 0012    QuickDraw Aux
  197. 0013    Print Manager
  198. 0014    Line Edit
  199. 0015    Dialog Manager
  200. 0016    Scrap Manager
  201. 0017    Standard File
  202. 0019    Note Synth
  203. 001A    Note Seq
  204. 001B    Font Manager
  205. 001C    List Manager
  206. 001D    ACE
  207. 001E    Resource Manager
  208. 0020    Midi
  209. 0021    Video Overlay
  210. 0022    Text Edit
  211. 0023    MIDI Synth
  212. 00FF    Debugger
  213.  
  214.  
  215.  
  216. GS/OS Call Names
  217.  
  218. Brought the list of GS/OS call names up to date for System Software 5.0.3.
  219.  
  220.  
  221. Removed this call:
  222.  
  223. $000E   ExpandPath (becuase there's no class-0 version)
  224.  
  225.  
  226. Added these class-1 call names:
  227.  
  228. $2029   Quit
  229. $2033   FSTSpecific
  230. $2034   AddNotifyProc
  231. $2035   DelNotifyProc
  232. $2036   DRename
  233. $2037   GetStdRefNum
  234. $2038   GetRefNum
  235. $2039   GetRefInfo
  236.  
  237.  
  238.  
  239.  
  240. What It Doesn't Do Yet
  241.  
  242.  
  243. Note--sometimes the debugger gets mysteriously disconnected from the
  244. Apple-Ctl-ESC vector.  If you can reproduce this, let me know.
  245.  
  246.  
  247. Holding down Option occasionally overrides a memory-protect area, but
  248. sometimes it crashes instead.
  249.  
  250.  
  251. Some of the help screens are incompelete or inaccurate.
  252.  
  253.  
  254. Templates currently limited to 64K.  If template file >64K, it gets left open
  255. by accident.
  256.  
  257.  
  258. There's a harmless problem where hitting SPACE to single-step an RTS
  259. sometimes doesn't do anything at all.
  260.  
  261.  
  262. Using X to execute a JSR real-time has problems sometimes.  It's been known
  263. to scramble the B register (if anyone has a reproducible case, let me know!),
  264. and I've seen it come back in $01/Fxxx space with the ROM enabled when the
  265. language card was supposed to be.
  266.  
  267.  
  268. Breakpoints don't work quite right in bank-switched memory, either (it doesn't
  269. store the original instruction into the right bank?).
  270.  
  271.  
  272. Should show OS call names on a JSL $E100B0 (examine stack if stepping, and look 
  273. for a PEA $xxxx in a disassembly).
  274.  
  275.  
  276. Install notify procedure so OS breaks still work after coming back from
  277. ProDOS 8.
  278.  
  279.  
  280. The debugger chains into the tool-dispatcher vectors its own way.  It should
  281. use the standard method defined in GS Technical Note #87.
  282.  
  283.  
  284. Should make the Init version take exactly 64K to avoid mucking up memory use.
  285. This will also fix problems where tool calls made from the same bank as GSBug
  286. never trigger a tool break.
  287.  
  288.  
  289. Will implement pseudo Tool calls to set and clear debugger breakpoints under 
  290. program control.
  291.  
  292.  
  293. May make the MEM locations labelable (and save labels in the config file).
  294.  
  295.  
  296. RHandleS template partially implemented?
  297.  
  298.  
  299. Unload should call UserShutDown on self (under ProDOS 8, just beep instead).
  300.  
  301.  
  302. Make sure that "\" for changing display modes is documented.
  303.  
  304.  
  305. Should load */System/System.Setup/GSBug.TMPL automatically.
  306.  
  307.  
  308.  
  309. Documentation
  310.  
  311.  
  312. The GSBug manual from APDA of 3/16/89 seems to be the latest there is.  All
  313. features not covered there should be in these release notes.
  314.  
  315.  
  316.  
  317. History
  318.  
  319.  
  320. This part of the document details all changes made to the debugger from version 
  321. 1.3b1 to 1.5b8.
  322.  
  323.  
  324. Bug Fixes:
  325.  
  326. Real Time Tool Breaks - The mechanism for using tool breaks real time has
  327. been modified, the old method never worked quite right, what used to happen
  328. was that when a tool break was to occur, the stub in the dispatch vector
  329. would simply jump into the debugger, this would cause the stack and processor
  330. not to be set as if they came from an interupt, and the next exit of the
  331. debugger would cause code execution to start at an inapropriate case, also
  332. the actual tracing of a tool break would also cause the debugger to
  333. improperly save the current registers, so that the stack/direct page and
  334. processor status might come back damaged from a tool break. The stub has
  335. been modified to now enter the debugger with a break instruction instead
  336. of jumping to the front. This seems to solve all real time tool break
  337. problems.
  338.  
  339. Error tool breaks - These also did not work well, and did not seem to be
  340. used by anyone anyway, so they have been removed to make room for OSBreaks.
  341.  
  342. Version 1.5b3:
  343. % display code was fixed so that the '*' would properly be displayed in
  344.   front of any toolbox glue that is detected.
  345. % Fixed template data display so that if the data being displayed crosses
  346.   a bank boundry, the data is properly followed into the new bank.
  347. % Modified the IN command so that it respects trigger counts of 0 and does
  348.   not insert real time breaks.
  349.  
  350. Version 1.5b5:
  351. % Added Glue tool break support. Now toolbreaks work for regular and glue
  352.   tool breaks. ErrorBreaks do not work for glue as they do not make a lot
  353.   of sense.
  354. % Made debugger work even when a DA window is open. See new features below.
  355. % Added keyClick so that you hear whenever the system draws a key from the
  356.   event queue. Also, cleaned up some comments.
  357.  
  358. Version 1.5b6:
  359. % Added new DebugStr toolcall that can be used to get more from the debugger.
  360.  
  361. Version 1.5b7:
  362. % Added support for real time conditional breaks.
  363. % Added OSBreaks.
  364. % Fixed the Debugger tool calls (like DebugStr ) so that they use the proper
  365.   tool numbers (they had the toolset number in the high byte instead of the
  366.   low byte) Documentation for them should also be right.
  367.  
  368. Version 1.5b8:
  369. % Added a debugger version and status call to the debugger tools.
  370. % Enhanced the OSBreak facility.
  371. % Removed the keyclicks because Dave complained.
  372.  
  373. Version 1.5b9:
  374. % Fixed some bugs.
  375.  
  376.  
  377. New Features:
  378.  
  379. DebugStr:
  380. This feature is designed to allow developers to better know where in their
  381. program the debugger was entered. The way this feature works is that if you
  382. want to enter the debugger programatically you can now also pass a string to
  383. the debugger which will be printed on the bottom line of the screen when the
  384. debugger is entered.
  385.  
  386. The way this mechanism works is a fake tool call that the debugger now
  387. supports. Since this looks like a normal tool call it can be easily called
  388. by any high level language as well as by assembly language.  This toolcall
  389. called DebugStr takes a single parameter, a pointer to a pascal string. When
  390. the tool call is made the debugger is entered as if you had put a break
  391. into your code, but the string you passed is displayed on the screen and
  392. the program counter has been bumped passed the tool call jsl. This way you
  393. can simply resume execution with two simple keystrokes (with the init
  394. version hit 'R' <return>).
  395.  
  396. Calling this new feature might look something like this
  397.  
  398.         PushLong #DebugStr
  399.         ldx #$09FF
  400.         jsl >$E10000
  401.  
  402.     ...
  403. DebugStr    str 'You are about to do blah.'
  404.  
  405. from pascal the same would be achieved by doing this...
  406.  
  407.         DebugStr('You are about to do blah.');
  408.  
  409. I would recommend that assembly language users use a macro to make the
  410. toolcall and call it _DebugStr.  MPW IIGS Pascal users could use the
  411. following to define the debugstr routine:
  412.  
  413.     Procedure DebugStr(theString:str255);
  414.         INLINE $09FFA2, $E1000022;
  415.  
  416. This call will also work when being called via the glue vector. 
  417. NOTE: Since this call is only available when the debugger is loaded you
  418. will ALWAYS want to be sure to remove ALL calls to the debugger before
  419. releasing your program (or even using it on machines that do not have a
  420. debugger installed).
  421.  
  422.  
  423. SetMileStone:
  424. SetMileStone operates exactly the same way as debugstr except that the
  425. debugger is not actually entered. This will allow tracking of random
  426. crashes by allowing you to call the SetMileStone routine with milestones
  427. that have been met. Any time the debugger is entered via a BRK instruction
  428. or thru the keyboard, the last string passed via the SetMileStone call will
  429. be displayed. The toolcall number for SetMileStone is $0AFF, the  MPW IIGS
  430. Pascal interface might look like this:
  431.  
  432.     Procedure SetMileStone (theString:str255);
  433.         INLINE $0AFFA2, $E1000022;
  434.  
  435.  
  436. DebugVersion, DebugStatus:
  437. These calls are added so that an application can identify the version of the
  438. debugger that is loaded and thus know what calls can be made to the debug
  439. tool. Currently, these calls are identical and return the same result. The
  440. DebugStatus call returns non-zero for true (as opposed to $FFFF which most
  441. people might want...) other than that these calls act the same as any other
  442. toolbox status or version call, each call requires a word space on the stack
  443. for the result which is on the top of the stack when the call completes. If
  444. a debugger is loaded that does not support this feature you will get a
  445. standard tool locator error. For version 1.5b8 the version number returned
  446. is $158F .As you might expect, this number will change as the debugger
  447. version changes and it will always go up, never down.
  448.  
  449.  
  450. Glue Snypher:
  451. Glue snypher is a routine that can recognize high level language tool calls
  452. that are made with the standard glue entry, when a call to glue is detected
  453. while disassembling an instruction the call to glue will be replaced with
  454. *_TooName in a manner similar to how real tool calls now work. Glue snypher
  455. is also used by the memory protect feature, if a glue call is detected
  456. while the standard toolbox memory protect range is on, the glue call will
  457. be treated as if it were a JSL >$e10000.  All glue entries MUST be a JSL
  458. to one of 3 standard types of glue that are shown below:
  459.  
  460.  
  461. ToolGlueType1   LDX #$ToolNum
  462.     JSL >$E10004
  463.     ...
  464.     RTL
  465.  
  466. ToolGlueType2   LDX #$ToolNum
  467.     JML CommonCall
  468.     ...
  469. CommonCall  JSL >$E10004
  470.     ...
  471.     RTL
  472.  
  473. ToolGlueType3   LDX #$ToolNum
  474.     JMP CommonCall
  475.  
  476. If any other types of glue calls are used, they will not be properly detected.
  477.  
  478.  
  479. Glue Breaks:
  480. In addition to glue snypher further support was added for high level
  481. languages by extending the tool break support to the glue vector ($E10004).
  482. Since error conditions are treated differently with glue (The second RTL
  483. ain't mine no more...) it seems unreasonable to also support error breaks
  484. via the glue vector. 
  485.  
  486.  
  487. OSBreaks:
  488. OSBreaks work very much the same way that tool breaks work with three
  489. exceptions. First, instead of breaking on a tool call they will break on
  490. a call to the OS. Next, you can NOT specify an OS break by name, only by
  491. number. Lastly, they are not supported in trace mode, only in real time
  492. mode.  To use OSBreaks you simply type setOSBrk #xxxx where xxxx is the 
  493. number of the OS routine that you want to break on. This number is matched
  494. exactly when an OS call is made, so if you do not know if the target call
  495. is class 0 or class 1 you must set the break for both calls. OSBreaks are
  496. supported via both vectors, inline and stackbased. The following is a
  497. list of commands that operate on OS breaks and what they do.
  498.  
  499. SetOSBrk - adds a number to the OS break list
  500. ClrOSBrk - Removes a given number from the OS break list
  501. ClrAllOSBrk - Removes all numbers from the OS break list
  502. OSBrkIn - enables real time scanning for OS breaks
  503. OSBrkOut - disables real time scanning of OS breaks
  504. ShowBrks - lists all tool and OS breaks currently set.
  505.  
  506.  
  507. DA Debugging support:
  508. In the past it has always been difficult to debug certain new desk
  509. accessories because they accept keystrokes, and keep the debugger from
  510. receiving them. I have added a patching mechanism to the system event
  511. call that is installed when the debugger is installed that fixes this
  512. problem. The way this feature now works is that if the caps lock key is
  513. down no keyboard events get passed to system event (and then to any open
  514. DA's) and the debugger will always get them. A side effect of this is that
  515. when the debugger screen is not active applications will get the same
  516. keystroke events if the CAPS LOCK key is down. As a gentle reminder of
  517. this feature, when installed, it will make your GS speaker click whenever
  518. a key is processed by getNextEvent.  The debugger used to click on every
  519. keystroke, regardless of the state of the CAPS LOCK key.  Dave complained
  520. enough that the debugger was changed to only click when keys are pressed
  521. if the CAPS LOCK key is down.
  522.  
  523.  
  524. New Template types:
  525.  
  526. We have added support for a few more data types in templates, these are
  527. mainly for use with GS/OS strings, but can also be used for any word
  528. length string. they are:
  529.  
  530.     InputStr:   This type will read the next word of data and treat it as
  531.                 a length word for string data that follows. The entire
  532.                 contents of the string will be displayed.
  533.  
  534.     OutputStr:  Similar to InputStr except that the first word is a buffer
  535.                 length and the second word is the string length. After the
  536.                 string is displayed the debugger will skip to the end of
  537.                 the buffer to find the next byte of data to process.
  538.  
  539.  
  540. RealTime Conditional Breakpoints:
  541.  
  542. The debugger now supports conditional real time breakpoints. In the past
  543. when a breakpoint was entered in the breakpoint list and you used the IN
  544. feature to make them work real time, the trigger count that you entered
  545. was ignored. Now, If you the trigger count is supported the same way it is
  546. supported in trace mode, that is, if you insert a real time breakpoint
  547. with a count higher than 1 it will break on the Nth execution of the
  548. opcode at that location. NOTE: Currently the following opcodes are not
  549. supported as real time conditional breakpoints: JSL(mem), JSR(mem),
  550. JSR(mem,x), JMP(mem), JMP(mem,x), RTI.
  551.  
  552. In addition to supporting a count value for real time break points, the
  553. debugger now also allows a simple conditional statement to be used instead.
  554. The debugger allows only one conditional statement at a time, but as many
  555. of the breakpoints can use it as you want. To enable the conditional
  556. statement (henceforth called IF) simply type an "i" when entering a
  557. breakpoints trigger value instead of a hex digit. To set the current IF
  558. use the command SetIF. the syntax of the SetIF command is as follows:
  559.  
  560.     SETIF {width} {Spec1}{Operator}{Spec2}
  561.  
  562. Legal {width} values
  563.      W  for word 
  564.      B  for byte
  565.  
  566. Legal {Operator} values
  567.     =   for is equal to
  568.     #   for is NOT equal to
  569.     <   for is less than
  570.     >   for is Greater than or equal to
  571.  
  572. Legal {Spec1} and {Spec2} values are
  573.     A,X,Y,S,D,P,B   for the corresponding register
  574.     $BBXXXX     as the address of a value in memory
  575.     #$XXXX      as a hexidecimal constant ({SPEC2} only)
  576.  
  577. Some examples of IFs
  578.  
  579.     SETIF W A<#$0101        (Break if the word in <A> is less than #$0101)
  580.     SETIF B $021234=$034321 (Break if the bytes at $02/1234 and $03/4321
  581.                              are the same.)
  582.  
  583. NOTE: Currently only long addresses are supported.
  584.